

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>1. Overview over MDAnalysis &mdash; MDAnalysis v0.7.5-devel documentation</title>
    <link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '0.7.5-devel',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="search" type="application/opensearchdescription+xml"
          title="Search within MDAnalysis v0.7.5-devel documentation"
          href="../_static/opensearch.xml"/>
    <link rel="shortcut icon" href="../_static/mdanalysis-logo.ico"/>
    <link rel="top" title="MDAnalysis v0.7.5-devel documentation" href="../index.html" />
    <link rel="next" title="2. Selection Commands" href="selections.html" />
    <link rel="prev" title="MDAnalysis documentation" href="../index.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="selections.html" title="2. Selection Commands"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="../index.html" title="MDAnalysis documentation"
             accesskey="P">previous</a> |</li>
        <li><a href="../index.html">MDAnalysis v0.7.5-devel documentation</a> &raquo;</li> 
      </ul>
    </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="../index.html">
              <img class="logo" src="../_static/mdanalysis-logo-200x150.png" alt="Logo"/>
            </a></p>
  <h3><a href="../index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">1. Overview over MDAnalysis</a><ul>
<li><a class="reference internal" href="#using-mdanalysis-in-python">1.1. Using MDAnalysis in python</a></li>
<li><a class="reference internal" href="#examples">1.2. Examples</a><ul>
<li><a class="reference internal" href="#included-trajectories">1.2.1. Included trajectories</a></li>
<li><a class="reference internal" href="#code-snippets">1.2.2. Code snippets</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="../index.html"
                        title="previous chapter">MDAnalysis documentation</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="selections.html"
                        title="next chapter">2. Selection Commands</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="../_sources/documentation_pages/overview.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" size="18" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="overview-over-mdanalysis">
<h1>1. Overview over MDAnalysis<a class="headerlink" href="#overview-over-mdanalysis" title="Permalink to this headline">¶</a></h1>
<p><strong>MDAnalysis</strong> is a Python package that provides classes to access
data in molecular dynamics trajectories. It is object oriented so it
treats atoms, groups of atoms, trajectories, etc as different
objects. Each object has a number of operations defined on itself
(also known as &#8220;methods&#8221;) and also contains values describing the
object (&#8220;attributes&#8221;). For example, a
<a class="reference internal" href="core/AtomGroup.html#MDAnalysis.core.AtomGroup.AtomGroup" title="MDAnalysis.core.AtomGroup.AtomGroup"><tt class="xref py py-class docutils literal"><span class="pre">AtomGroup</span></tt></a> object has a
<a class="reference internal" href="core/AtomGroup.html#MDAnalysis.core.AtomGroup.AtomGroup.centerOfMass" title="MDAnalysis.core.AtomGroup.AtomGroup.centerOfMass"><tt class="xref py py-meth docutils literal"><span class="pre">centerOfMass()</span></tt></a> method that
returns the center of mass of the group of atoms. It also contains an
attribute called <a class="reference internal" href="core/AtomGroup.html#MDAnalysis.core.AtomGroup.AtomGroup.residues" title="MDAnalysis.core.AtomGroup.AtomGroup.residues"><tt class="xref py py-attr docutils literal"><span class="pre">residues</span></tt></a>
that lists all the residues that belong to the group. Using methods
such as <a class="reference internal" href="core/AtomGroup.html#MDAnalysis.core.AtomGroup.AtomGroup.selectAtoms" title="MDAnalysis.core.AtomGroup.AtomGroup.selectAtoms"><tt class="xref py py-meth docutils literal"><span class="pre">selectAtoms()</span></tt></a>
(which uses <a class="reference external" href="http://www.charmm.org/html/documentation/c34b1/select.html">CHARMM-style</a> atom <a class="reference internal" href="selections.html#selection-commands-label"><em>Selection Commands</em></a>) one
can create new objects (in this case, another
<a class="reference internal" href="core/AtomGroup.html#MDAnalysis.core.AtomGroup.AtomGroup" title="MDAnalysis.core.AtomGroup.AtomGroup"><tt class="xref py py-class docutils literal"><span class="pre">AtomGroup</span></tt></a>).</p>
<p>A typical usage pattern is to iterate through a trajectory and analyze
coordinates for every frame. In the following example the end-to-end distance
of a protein and the radius of gyration of the backbone atoms are calculated:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">MDAnalysis</span>
<span class="kn">from</span> <span class="nn">MDAnalysis.tests.datafiles</span> <span class="kn">import</span> <span class="n">PSF</span><span class="p">,</span><span class="n">DCD</span>   <span class="c"># test trajectory</span>
<span class="kn">import</span> <span class="nn">numpy.linalg</span>
<span class="n">u</span> <span class="o">=</span> <span class="n">MDAnalysis</span><span class="o">.</span><span class="n">Universe</span><span class="p">(</span><span class="n">PSF</span><span class="p">,</span><span class="n">DCD</span><span class="p">)</span>                 <span class="c"># always start with a Universe</span>
<span class="n">nterm</span> <span class="o">=</span> <span class="n">u</span><span class="o">.</span><span class="n">s4AKE</span><span class="o">.</span><span class="n">N</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>   <span class="c"># can access structure via segid (s4AKE) and atom name</span>
<span class="n">cterm</span> <span class="o">=</span> <span class="n">u</span><span class="o">.</span><span class="n">s4AKE</span><span class="o">.</span><span class="n">C</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>  <span class="c"># ... takes the last atom named &#39;C&#39;</span>
<span class="n">bb</span> <span class="o">=</span> <span class="n">u</span><span class="o">.</span><span class="n">selectAtoms</span><span class="p">(</span><span class="s">&#39;protein and backbone&#39;</span><span class="p">)</span>  <span class="c"># a selection (a AtomGroup)</span>
<span class="k">for</span> <span class="n">ts</span> <span class="ow">in</span> <span class="n">u</span><span class="o">.</span><span class="n">trajectory</span><span class="p">:</span>     <span class="c"># iterate through all frames</span>
  <span class="n">r</span> <span class="o">=</span> <span class="n">cterm</span><span class="o">.</span><span class="n">pos</span> <span class="o">-</span> <span class="n">nterm</span><span class="o">.</span><span class="n">pos</span> <span class="c"># end-to-end vector from atom positions</span>
  <span class="n">d</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">norm</span><span class="p">(</span><span class="n">r</span><span class="p">)</span>  <span class="c"># end-to-end distance</span>
  <span class="n">rgyr</span> <span class="o">=</span> <span class="n">bb</span><span class="o">.</span><span class="n">radiusOfGyration</span><span class="p">()</span>  <span class="c"># method of a AtomGroup; updates with each frame</span>
  <span class="k">print</span> <span class="s">&quot;frame = </span><span class="si">%d</span><span class="s">: d = </span><span class="si">%f</span><span class="s"> Angstroem, Rgyr = </span><span class="si">%f</span><span class="s"> Angstroem&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">ts</span><span class="o">.</span><span class="n">frame</span><span class="p">,</span> <span class="n">d</span><span class="p">,</span> <span class="n">rgyr</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="using-mdanalysis-in-python">
<h2>1.1. Using MDAnalysis in python<a class="headerlink" href="#using-mdanalysis-in-python" title="Permalink to this headline">¶</a></h2>
<p>If you&#8217;ve installed MDAnalysis in the standard python modules location, load
from within the interpreter:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">MDAnalysis</span> <span class="kn">import</span> <span class="o">*</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">MDAnalysis</span>
</pre></div>
</div>
<p>The idea behind MDAnalysis is to get trajectory data into <a class="reference external" href="http://numpy.scipy.org">NumPy</a>
<a class="reference external" href="http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v2.0.dev-4fb84e7)"><tt class="xref py py-class docutils literal"><span class="pre">numpy.ndarray</span></tt></a> arrays, where it can then be easily manipulated using
all the power in <a class="reference external" href="http://numpy.scipy.org">NumPy</a> and <a class="reference external" href="http://www.scipy.org/">SciPy</a>.</p>
<p>MDAnalysis works well both in scripts and in interactive use. The developers
very much recommend using MDAnalysis from within the <a class="reference external" href="http://ipython.scipy.org/">IPython</a> Python shell.  It
allows one to interactively explore the objects (using TAB-completion and
online help), do analysis and immediately plot results. The examples in this manual
are typically run from an interactive <strong class="program">ipython</strong> session.</p>
<p>Invariably, a MDAnalysis session starts with loading data into the
<a class="reference internal" href="core/AtomGroup.html#MDAnalysis.core.AtomGroup.Universe" title="MDAnalysis.core.AtomGroup.Universe"><tt class="xref py py-class docutils literal"><span class="pre">Universe</span></tt></a> class (which can be accessed
as <tt class="xref py py-class docutils literal"><span class="pre">MDAnalysis.Universe</span></tt>):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">MDAnalysis</span> <span class="kn">import</span> <span class="o">*</span>
<span class="n">universe</span> <span class="o">=</span> <span class="n">Universe</span><span class="p">(</span><span class="n">topology</span><span class="p">,</span> <span class="n">trajectory</span><span class="p">)</span>
</pre></div>
</div>
<ul class="simple">
<li>The <em>topology</em> file lists the atoms and residues (and also their
connectivity). It can be a CHARMM/XPLOR/NAMD PSF file or a coordinate file
such as a Protein Databank Brookhaven PDB file, a CHARMM card coordinate file
(CRD), or a GROMOS/Gromacs GRO file.</li>
<li>The <em>trajectory</em> contains a list of coordinates in the order defined in the
<em>topology</em>. It can either be a single frame (PDB, CRD, and GRO are all read)
or a time series of coordinate frames such as a CHARMM/NAMD/LAMMPS DCD
binary file, a Gromacs XTC/TRR trajectory, or a XYZ trajectory (possibly
compressed with gzip or bzip2).</li>
</ul>
<p>For the remainder of this introduction we are using a short example trajectory
that is provided with MDAnalysis (as part of the <a class="reference external" href="http://code.google.com/p/mdanalysis/wiki/UnitTests">MDAnalysis test suite</a>). The
trajectory is loaded with</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">MDAnalysis</span> <span class="kn">import</span> <span class="n">Universe</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">MDAnalysis.tests.datafiles</span> <span class="kn">import</span> <span class="n">PSF</span><span class="p">,</span><span class="n">DCD</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">u</span> <span class="o">=</span> <span class="n">Universe</span><span class="p">(</span><span class="n">PSF</span><span class="p">,</span> <span class="n">DCD</span><span class="p">)</span>
</pre></div>
</div>
<p>(The <tt class="docutils literal"><span class="pre">&gt;&gt;&gt;</span></tt> signs are the Python input prompt and are not to be typed; they
just make clear in the examples what is input and what is output.)</p>
<p>The <a class="reference internal" href="core/AtomGroup.html#MDAnalysis.core.AtomGroup.Universe" title="MDAnalysis.core.AtomGroup.Universe"><tt class="xref py py-class docutils literal"><span class="pre">Universe</span></tt></a> contains a number of important attributes,
the most important ones of which is
<tt class="xref py py-attr docutils literal"><span class="pre">atoms</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">u</span><span class="o">.</span><span class="n">atoms</span>
<span class="go">&lt;AtomGroup with 3341 atoms&gt;</span>
</pre></div>
</div>
<p><tt class="xref py py-attr docutils literal"><span class="pre">Universe.atoms</span></tt> is a
<a class="reference internal" href="core/AtomGroup.html#MDAnalysis.core.AtomGroup.AtomGroup" title="MDAnalysis.core.AtomGroup.AtomGroup"><tt class="xref py py-class docutils literal"><span class="pre">AtomGroup</span></tt></a> and can be thought of as
list consisting of <a class="reference internal" href="core/AtomGroup.html#MDAnalysis.core.AtomGroup.Atom" title="MDAnalysis.core.AtomGroup.Atom"><tt class="xref py py-class docutils literal"><span class="pre">Atom</span></tt></a>
objects. The <a class="reference internal" href="core/AtomGroup.html#MDAnalysis.core.AtomGroup.Atom" title="MDAnalysis.core.AtomGroup.Atom"><tt class="xref py py-class docutils literal"><span class="pre">Atom</span></tt></a> is the
elementary and fundamental object in MDAnalysis.</p>
<p>The <tt class="xref py py-attr docutils literal"><span class="pre">MDAnalysis.Universe.trajectory</span></tt> attribute gives access to the coordinates
over time:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">u</span><span class="o">.</span><span class="n">trajectory</span>
<span class="go">&lt; DCDReader &#39;/..../MDAnalysis/tests/data/adk_dims.dcd&#39; with 98 frames of 3341 atoms (0 fixed) &gt;</span>
</pre></div>
</div>
<p>Finally, the <tt class="xref py py-meth docutils literal"><span class="pre">MDAnalysis.Universe.selectAtoms()</span></tt> method generates a new
<a class="reference internal" href="core/AtomGroup.html#MDAnalysis.core.AtomGroup.AtomGroup" title="MDAnalysis.core.AtomGroup.AtomGroup"><tt class="xref py py-class docutils literal"><span class="pre">AtomGroup</span></tt></a> according to a selection criterion</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">calphas</span> <span class="o">=</span> <span class="n">u</span><span class="o">.</span><span class="n">selectAtoms</span><span class="p">(</span><span class="s">&quot;name CA&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">calphas</span>
<span class="go">&lt;AtomGroup with 214 atoms&gt;</span>
</pre></div>
</div>
<p>as described in <a class="reference internal" href="selections.html#selection-commands-label"><em>Selection Commands</em></a>.</p>
</div>
<div class="section" id="examples">
<h2>1.2. Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<p>The easiest way to get started with MDAnalysis is to read this
introduction and the chapter on <a class="reference internal" href="selections.html#selection-commands-label"><em>Selection Commands</em></a> and then
explore the package interactively in <a class="reference external" href="http://ipython.scipy.org/">IPython</a> or another interactive
Python interpreter.</p>
<div class="section" id="included-trajectories">
<h3>1.2.1. Included trajectories<a class="headerlink" href="#included-trajectories" title="Permalink to this headline">¶</a></h3>
<p>MDAnalysis comes with a number of real trajectories for testing. You
can also use them to explore the functionality and ensure that
everything is working properly:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">MDAnalysis</span> <span class="kn">import</span> <span class="o">*</span>
<span class="kn">from</span> <span class="nn">MDAnalysis.tests.datafiles</span> <span class="kn">import</span> <span class="n">PSF</span><span class="p">,</span><span class="n">DCD</span><span class="p">,</span> <span class="n">PDB</span><span class="p">,</span><span class="n">XTC</span>
<span class="n">u_dims_adk</span> <span class="o">=</span> <span class="n">Universe</span><span class="p">(</span><span class="n">PSF</span><span class="p">,</span><span class="n">DCD</span><span class="p">)</span>
<span class="n">u_eq_adk</span> <span class="o">=</span> <span class="n">Universe</span><span class="p">(</span><span class="n">PDB</span><span class="p">,</span> <span class="n">XTC</span><span class="p">)</span>
</pre></div>
</div>
<p>The PSF and DCD file are a closed-form-to-open-form transition of
Adenylate Kinase (from <a class="reference internal" href="#beckstein2009">[Beckstein2009]</a>) and the PDB+XTC file are ten
frames from a Gromacs simulation of AdK solvated in TIP4P water with
the OPLS/AA force field.</p>
<table class="docutils citation" frame="void" id="beckstein2009" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[Beckstein2009]</a></td><td>O. Beckstein, E.J. Denning, J.R. Perilla, and
T.B. Woolf. Zipping and Unzipping of Adenylate
Kinase: Atomistic Insights into the Ensemble of
Open &lt;&#8211;&gt; Closed Transitions. <em>J Mol Biol</em> <strong>394</strong>
(2009), 160&#8211;176, doi:<a class="reference external" href="http://dx.doi.org/10.1016/j.jmb.2009.09.009">10.1016/j.jmb.2009.09.009</a></td></tr>
</tbody>
</table>
</div>
<div class="section" id="code-snippets">
<h3>1.2.2. Code snippets<a class="headerlink" href="#code-snippets" title="Permalink to this headline">¶</a></h3>
<p>The source code distribution comes with a directory <a class="reference external" href="http://code.google.com/p/mdanalysis/source/browse/#svn%2Ftrunk%2Fexamples">examples</a> that
contains a number of code snippets that show how to use certain
aspects of MDAnalysis.</p>
<p>For instance, there is code that shows how to</p>
<ul class="simple">
<li>fit a trajectory to a reference structure using the QCP
RMSD-alignment code in <a class="reference internal" href="core/qcprot.html#module-MDAnalysis.core.qcprot" title="MDAnalysis.core.qcprot"><tt class="xref py py-mod docutils literal"><span class="pre">MDAnalysis.core.qcprot</span></tt></a>
(<a class="reference external" href="http://code.google.com/p/mdanalysis/source/browse/trunk/examples/rmsfit_qcp.py">rmsfit_qcp.py</a>);</li>
<li>do a block-averaging error analysis (<a class="reference external" href="http://code.google.com/p/mdanalysis/source/browse/trunk/examples/blocks.py">blocks.py</a>);</li>
<li>calculate a potential profile across a membrane (<a class="reference external" href="http://code.google.com/p/mdanalysis/source/browse/trunk/examples/potential_profile.py">potential_profile.py</a>);</li>
<li>get the lipid composition of the individual leaflets of a bilayer
using <tt class="xref py py-mod docutils literal"><span class="pre">MDAnalysis.analysis.leaflets</span></tt> (<a class="reference external" href="http://code.google.com/p/mdanalysis/source/browse/trunk/examples/membrane-leaflets.py">membrane-leaflets.py</a>);</li>
<li>define the multimeric states of a number of transmembrane peptides
via clustering (<a class="reference external" href="http://code.google.com/p/mdanalysis/source/browse/trunk/examples/multimers-analysis.py">multimers-analysis.py</a>);</li>
<li>convert between trajectory formats;</li>
<li>use MDAnalysis for simple model building (<a class="reference external" href="http://code.google.com/p/mdanalysis/source/browse/trunk/examples/make_MthK_tetramer.py">make_MthK_tetramer.py</a>);</li>
</ul>
<p>and more.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="selections.html" title="2. Selection Commands"
             >next</a> |</li>
        <li class="right" >
          <a href="../index.html" title="MDAnalysis documentation"
             >previous</a> |</li>
        <li><a href="../index.html">MDAnalysis v0.7.5-devel documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2005-2011, Naveen Michaud-Agrawal, Elizabeth J. Denning, Joshua Adelman,
    Christian Beckstein (logo), David Caplan, Jan Domański, Philip Fowler,
    Joseph Goose, Benjamin Hall, Danny Parton, Tyler Reddy, Paul Rigor,
    and Oliver Beckstein.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
    </div>
  </body>
</html>